/*!
 * \file scope_guard.hpp
 * \brief 作用域守护类实现
 *
 * \details 提供RAII作用域守护机制，确保在作用域结束时自动执行清理操作。
 *          
 *          scope_guard是一个重要的资源管理工具，用于：
 *          - 自动执行退出时的清理操作
 *          - 异常安全的资源管理
 *          - 简化复杂的异常处理逻辑
 *          - 确保代码的异常安全性
 *          
 *          核心特性：
 *          - RAII机制：构造时注册，析构时执行
 *          - 异常安全：即使发生异常也能正确执行清理
 *          - 可禁用：支持条件性执行清理操作
 *          - 不可复制：防止意外的多次执行
 *          
 *          典型用法：
 *          \\code
 *          {
 *              scope_guard guard([](){
 *                  // 清理操作
 *                  cleanup_resources();
 *              });
 *              
 *              // 执行可能抛出异常的操作
 *              risky_operation();
 *              
 *              // 如果成功，可以禁用清理
 *              guard.disable();
 *          } // 作用域结束时自动执行清理（如果未禁用）
 *          \\endcode
 *
 * Copyright (c) 2005-2007 Philipp Henkel
 *
 * Use, modification, and distribution are  subject to the
 * Boost Software License, Version 1.0. (See accompanying  file
 * LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 *
 * http://threadpool.sourceforge.net
 *
 */


#ifndef THREADPOOL_DETAIL_SCOPE_GUARD_HPP_INCLUDED
#define THREADPOOL_DETAIL_SCOPE_GUARD_HPP_INCLUDED



#include <boost/function.hpp>


namespace boost { namespace threadpool { namespace detail 
{

/*!
 * \brief 作用域守护类
 * 
 * \details scope_guard提供RAII作用域管理机制，在析构时自动执行
 *          预定义的清理函数。这是一个重要的异常安全工具。
 *          
 *          设计特点：
 *          - 基于RAII原则的资源管理
 *          - 异常安全：无论正常退出还是异常都会执行
 *          - 条件执行：可通过disable()方法取消执行
 *          - 不可复制：继承boost::noncopyable防止误用
 *          
 *          适用场景：
 *          - 临时资源的自动清理
 *          - 异常处理中的回滚操作
 *          - 复杂函数的统一退出处理
 *          - 线程同步中的锁释放
 */
class scope_guard
: private boost::noncopyable
{
	function0<void> const m_function;   //!< 在作用域结束时执行的函数
	bool                  m_is_active;  //!< 守护是否处于活动状态

public:
	/*!
	 * \brief 构造函数
	 * \param call_on_exit 在作用域结束时调用的函数
	 * 
	 * \details 创建作用域守护对象，注册在析构时要执行的清理函数。
	 *          默认情况下守护处于活动状态，会在析构时执行函数。
	 */
	scope_guard(function0<void> const & call_on_exit)
	: m_function(call_on_exit)
	, m_is_active(true)
	{
	}

	/*!
	 * \brief 析构函数
	 * 
	 * \details 如果守护处于活动状态且函数有效，则执行注册的清理函数。
	 *          这确保了即使在异常情况下也能进行必要的清理操作。
	 */
	~scope_guard()
	{
		if(m_is_active && m_function)
		{
			m_function();
		}
	}

	/*!
	 * \brief 禁用守护
	 * 
	 * \details 将守护设置为非活动状态，这样在析构时就不会执行
	 *          清理函数。通常在操作成功完成后调用，表示不需要
	 *          执行回滚或清理操作。
	 */
	void disable()
	{
		m_is_active = false;
	}
};






} } } // namespace boost::threadpool::detail

#endif // THREADPOOL_DETAIL_SCOPE_GUARD_HPP_INCLUDED


